任务报告推送

注册回调即可实时接收任务报告，新增集团客户推送支持。

兼容性：2025‑05‑15（含）之后新建或重新保存的订阅将采用本文描述的 新顶级字段格式。
已生效的旧订阅保持两级结构（appId + payload），功能不受影响。
新顶级字段（与 appId、payload 同级）。

接入流程

第一步：配置回调地址

登录开发者中心，进入 企业回调地址。本页对应页面上的「任务报告回调地址」区块，与事件回调地址相互独立。
指定 推送账号：该账号必须是本客户的开发者，也是唯一能修改本页的人。推送范围由它决定——只有直接绑定到该推送账号的机器人，其任务报告才会推送；仅归属本客户但未直接绑定给该账号的机器人不会推送。事件与任务共用同一个推送账号。
点击区块内的修改，填写回调 url，打开推送开关后点击保存。
保存后平台签发该订阅的 AppId 与 Secret。Secret 只在重置后可再次查看，请当场保存。

开发者中心「企业回调地址」页面：任务报告回调地址与事件回调地址各自独立配置，含 AppId、Secret、回调地址与推送开关

第二步：实现验签

推送会携带 X-Gausium-App-Id、X-Gausium-Timestamp、X-Gausium-Nonce、X-Gausium-Signature 四个请求头，验签算法与中英文示例见回调验签。

第三步：联调

点击区块内的测试，平台会向填写的地址 POST 一次探测包。返回 2xx 且验签通过，说明链路已通。

第四步：接收并处理推送

链路打通后即可按下方字段表解析任务报告。几个高频问题建议先读：

任务报告的时间字段是什么格式：推送是 Unix 毫秒，查询接口是秒。
任务报告里没有 taskId / planId，正常吗：部分机型与版本不上报。
durationSeconds 是 0，是不是算错了：该字段只统计真正作业时间。

推送只是实时增量

推送覆盖新生成的任务报告。历史报告请用分页查询任务报告，报告地图图片请用查询任务报告地图图片。

回调注册要求

语言：符合 IETF BCP 47（如 en-US、zh-CN）。
回调：
- url 例如 https://{{host}}/callback，HTTP 方法 POST。
- appId 例如 24416c36-d9c7-4d74-a047-d6ca461fxxxx（用于鉴权。由高仙签发后提供）。

示例 curl

curl --location 'https://{{host}}/callback' \
--header 'accept: */*' \
--header 'Content-Type: application/json' \
--data '{
  "appId": "24416c36-aaaa-4d74-aaaa-d6ca461faaaa",
  "payload": {
    "serialNumber": "TEST00-0000-000-XXXX",
    "modelTypeCode": "Scrubber S1",
    "taskReport": {
      "id": "684c183c-4ad9-467b-ac7c-55835255AAAA",
      "taskId": "233123123-d9c7-4d74-a047-d6ca461faaaa",
      "planId": "233123123-d9c7-4d74-a047-d6ca461faaaa",
      "taskInstanceId": "893cbadf-3bb1-45be-b7ef-d590d54fAAAA",
      "displayName": "ceshi2",
      "startTime": 1714124784000,
      "endTime": 1714124890000,
      "robot": "S2153",
      "robotSerialNumber": "TEST00-0000-000-XXXX",
      "operator": "admin",
      "completionPercentage": 0.156,
      "durationSeconds": 106,
      "plannedCleaningAreaSquareMeter": 67.425,
      "actualCleaningAreaSquareMeter": 10.548,
      "efficiencySquareMeterPerHour": 407.965,
      "plannedPolishingAreaSquareMeter": null,
      "actualPolishingAreaSquareMeter": null,
      "waterConsumptionLiter": 0.0,
      "startBatteryPercentage": 38.0,
      "endBatteryPercentage": 38.0,
      "consumablesResidualPercentage": {
        "brush": 100.0,
        "filter": 100.0,
        "suctionBlade": 100.0
      },
      "cleaningMode": "清扫",
      "taskEndStatus": 1,
      "subTasks": [
        {
          "mapId": "370192bd-fe7f-40d0-8d0a-4360415bb8cf",
          "mapName": "ceshi2",
          "actualCleaningAreaSquareMeter": 10.548,
          "taskId": "233123123-d9c7-4d74-a047-d6ca461faaaa"
        }
      ],
      "taskReportPngUri": "https://bot.release.gs-robot.com/robot-task/task/report/png/v2/en/684c183c-4ad9-467b-ac7c-55835255aaaa",
      "areaNameList": "2_area1、area2、area3、area4,3_area1、area2、area3"
    }
  }
}'

顶级字段说明

字段	类型	描述
`appId`	String	用于鉴权，保持不变
`payload`	Object	业务数据，结构与旧版保持一致

参数描述

字段名称	类型	描述	示例
payload.serialNumber	String	机器人序列号	TEST00-0000-000-XXXX
payload.modelTypeCode	String	机器人型号代码	Scrubber 50H
payload.taskReport	Object	任务报告	—
payload.taskReport.id	String	任务报告 ID	684c183c-4ad9-467b-ac7c-55835255AAAA
payload.taskReport.taskId	String	静态任务 ID	233123123-d9c7-4d74-a047-d6ca461faaaa
payload.taskReport.planId	String	调度计划 ID	233123123-d9c7-4d74-a047-d6ca461faaaa
payload.taskReport.taskInstanceId	String	任务实例 ID	893cbadf-3bb1-45be-b7ef-d590d54fAAAA
payload.taskReport.displayName	String	任务可读名称	10楼清洁任务
payload.taskReport.startTime	Long	任务开始时间戳（毫秒）	1714290913000
payload.taskReport.endTime	Long	任务结束时间戳（毫秒）	1714290952000
payload.taskReport.robot	String	机器人可读名称	S2153
payload.taskReport.robotSerialNumber	String	机器人序列号	GS000-XXXX-XXX-XXXX
payload.taskReport.operator	String	任务操作员	Mike
payload.taskReport.completionPercentage	Double	完成百分比（0‑1）	0.55
payload.taskReport.durationSeconds	Integer	持续时间（秒）	300
payload.taskReport.plannedCleaningAreaSquareMeter	Double	计划清洁面积（㎡）	200.5
payload.taskReport.actualCleaningAreaSquareMeter	Double	实际清洁面积（㎡）	100.2
payload.taskReport.efficiencySquareMeterPerHour	Double	清洁效率（㎡/h）	300.7
payload.taskReport.plannedPolishingAreaSquareMeter	Double	计划抛光面积（㎡）	200.5
payload.taskReport.actualPolishingAreaSquareMeter	Double	实际抛光面积（㎡）	200.5
payload.taskReport.waterConsumptionLiter	Double	水耗（L）	5.0
payload.taskReport.startBatteryPercentage	Double	起始电量（%）	70.0
payload.taskReport.endBatteryPercentage	Double	结束电量（%）	40.0
payload.taskReport.consumablesResidualPercentage	Object	消耗品剩余百分比	—
payload.taskReport.consumablesResidualPercentage.brush	Double	刷子寿命（%）	50.0
payload.taskReport.consumablesResidualPercentage.filter	Double	过滤器寿命（%）	50.0
payload.taskReport.consumablesResidualPercentage.suctionBlade	Double	吸尘刮刀寿命（%）	50.0
payload.taskReport.cleaningMode	String	清洁模式	扫地
payload.taskReport.taskEndStatus	Integer	结束状态：-1未知，0正常，1手动，2异常，3启动失败	0
payload.taskReport.subTasks	Array	子任务列表	—
payload.taskReport.subTasks[0].mapId	String	地图 ID	370192bd-fe7f-40d0-8d0a-4360415baaaa
payload.taskReport.subTasks[0].mapName	String	地图名称	测试地图
payload.taskReport.subTasks[0].actualCleaningAreaSquareMeter	Double	实际清洁面积（㎡）	10.0
payload.taskReport.subTasks[0].taskId	String	子任务 ID	233123123-d9c7-4d74-a047-d6ca461faaaa
payload.taskReport.taskReportPngUri	String	任务报告 PNG URI	https://bot.gs-robot.com/robot-task/task/report/png/v2/en/47e3628b-a2b9-4124-bbbc-45e0d4bfaaaa
payload.taskReport.areaNameList	String	分区名称列表（floor_area1_area2...）	2_area1、area2、area3

接入流程​

第一步：配置回调地址​

第二步：实现验签​

第三步：联调​

第四步：接收并处理推送​

回调注册要求​

示例 curl​

顶级字段说明​

参数描述​